feat(mcp): serve a usage spec to an agent over stdio - #746

sequenceDiagram
  participant MCPClient
  participant UsageMcp
  participant SpecServer
  participant UsageSpec
  MCPClient->>UsageMcp: Send JSON-RPC over stdin
  UsageMcp->>SpecServer: Start MCP stdio transport
  SpecServer->>UsageSpec: Resolve commands and flags
  SpecServer-->>MCPClient: Return tool response over stdout

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands.}

Greptile Summary

Adds a local stdio MCP server for querying usage specifications.

• Introduces list_commands and describe_command tools with command, argument, flag, and effect metadata.
• Rejects stdin-based spec loading because stdin is reserved for MCP transport.
• Exposes parser-aligned inherited flag resolution through usage::available_flags.
• Registers the new command and regenerates CLI documentation, manpage, Fig completions, and dependency metadata.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

_{Reviews (5): Last reviewed commit: "fix(mcp): make the two tools agree on ho..." | Re-trigger Greptile}

Switched the implementation to rmcp, matching mise mcp and fnox mcp.

My original reason for hand-rolling the protocol — avoiding an async runtime in a synchronous CLI — was asserted rather than measured. Measured, the cost is binary size and nothing else:

The tokio runtime is built inside mcp run, so no other subcommand pays for it. In exchange the server inherits version negotiation, pagination, cancellation, tools/list schemas generated from the params structs, and protocol-vs-tool error framing, and mcp.rs loses ~170 lines.

Two bugs surfaced while doing it:

• get_info now sets server_info explicitly. rmcp's default is Implementation::from_build_env(), whose env! expands inside the rmcp crate — so a server that omits it introduces itself to clients as rmcp 2.2.0. (mise mcp has this today; worth a separate fix.)
• --file - is rejected instead of accepted. It reads stdin to EOF, which is the transport the server then wants to serve on.

Verified end to end against a real client handshake — initialize → notifications/initialized → tools/list → tools/call — returning {"name":"usage","version":"4.0.0"}, protocol 2025-06-18, both tools with generated schemas, and effect present on the command and its flags.

This comment was generated by an AI coding assistant.

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/​tokio@​1.53.1
	cargo/​rmcp@​2.2.0

View full report

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: cargo tokio is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: Cargo.lock → cargo/tokio@1.53.1 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore cargo/tokio@1.53.1. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

Addressed the review:

Stdin spec exhausts MCP stream (cursor, greptile) — fixed in 4d831d9. --file - is rejected outright rather than producing a session that ends before it begins.

Inherited global flags are omitted (greptile) — correct and fixed in e9bc59f. usage resolves ancestors' global=#true flags while parsing an invocation instead of copying them onto each subcommand (parse.rs:40), so cmd.flags was short by exactly the options an agent reaches for. describe_command now appends them marked "inherited": true, and a nearer redefinition shadows a farther one the way the parser resolves it — otherwise a subcommand that redefines a global without an effect would be reported as carrying the global's.

Describe exposes hidden commands (cursor) — deliberate, now commented and tested rather than incidental. list_commands omits hidden subtrees because they aren't documented paths. But an agent that names a hidden command already knows it exists — it saw it in a script or in shell history — and refusing to describe it doesn't stop the run, it just removes the effect from what the agent knows before running. The response carries "hidden": true so the caller can weigh it.

Verified end to end against a client handshake; pitchfork daemons remove now reports the inherited --yes with its effect: write.

This comment was generated by an AI coding assistant.

Rebased onto main (which now has #747) and fixed the flag resolution. cursor and greptile were both right, and my previous fix was worse than the bug it replaced.

I walked the ancestor chain by hand and let a nearer declaration shadow a farther one. merge_subcommand_flags does the opposite: a non-global re-declaration that shares a global's long name is the same logical flag, so the global's declaration survives and only the re-declaration's extra aliases are unioned in. A subcommand re-declaring -y --yes was therefore reported as effect: null when the flag actually carries the global's write — telling an agent a consequential flag is free of consequence, which is the precise failure this server exists to prevent.

The fix isn't to restate those rules more carefully. usage::available_flags(chain) now exposes the parser's own resolution and describe_command calls it, with a test asserting it agrees with parse_partial for every command in a spec so the two can't drift.

Two things fell out:

• The merge can leave one logical flag under two Arcs — the merged declaration on the long key, the pre-merge one on the short key, because the !Arc::ptr_eq guard sees the freshly-merged flag as "a different global". Harmless for parsing (lookups are by key) but visible to anything listing flags, so available_flags collapses by name after the pointer dedup.
• "inherited" is removed from the output. Under these rules there's no clean local-vs-inherited split, so the field could only be another small lie. "global" already tells the caller the flag is accepted everywhere.

Verified end to end: a spec with a long-only global --yes effect="write" re-declared as a non-global -y --yes on a subcommand now returns one flag, effect: write, with the -y short unioned in.

This comment was generated by an AI coding assistant.

Rebased onto main (which brought #751) and fixed the path inconsistency.

Command path format inconsistent (cursor) — correct. list_commands emitted "daemons remove" while describe_command answered "pitchfork daemons remove", so an agent doing the obvious thing — read the list, describe an entry — got a tool error on a command that exists.

describe_command now reports the path alone with bin beside it, matching list_commands. A test walks every row of list_commands through describe_command and asserts the name comes back unchanged, so the two ends can't drift apart again.

A leading binary name is accepted too, since an agent that has seen the CLI in a shell will write the whole line. It's only skipped when the root has no subcommand by that name — a CLI with a usage usage keeps resolving its own command rather than losing it to the prefix, and there's a test for that.

One thing worth reporting: the rebase brought #751's nothing_is_unclassified_by_accident test, and it failed immediately on mcp — the new command this PR adds. That is exactly what that guard is for, one day after it landed. Classified read: every tool this serves only reads the spec it was handed. mise mcp stays unclassified by contrast, because it serves a tool that runs tasks.

Verified against cli/usage.usage.kdl itself, which now carries #751's effects:

describe_command "generate markdown"        → command="generate markdown"  effect=read  --out-file effect=write
describe_command "usage generate markdown"  → command="generate markdown"  effect=read  --out-file effect=write

This comment was generated by an AI coding assistant.

Instruction counts

2 benchmark(s) above the 1% gate: markdown +7.16%, startup +6.03%

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{259021a981f1 vs d97b2c792735 · measured on the runner, not pushed to the history.}

The perf gate is red: startup +6.03%, markdown +7.16%. I split it into what caused what, because the two are different problems and only one of them is this PR's code.

Method: build main and this branch, then run the same binary against both spec files, 250 runs each, medians. Wall clock, not instructions — but the ratios land within 0.2pp of CI's instruction deltas, which is closer agreement than the 4-20% run-to-run noise would let happen by chance.

markdown is the corpus again, not the code. Holding the binary fixed and swapping only the spec accounts for 6.73 of the 7.34 points. This PR adds a whole command — mcp, with a long_help block — to a CLI that had 15, and the bench parses that spec and renders a page per command. One more command out of sixteen is ~6%. Same structural thing I flagged on #751: adding a command is a gate failure by construction.

startup is real and it's mine. +6.13% is entirely binary weight — 8.43 MB → 11.36 MB from linking rmcp, tokio and schemars. Swapping the binary while holding the spec fixed moves markdown by only 0.58%, so it isn't spec parsing; it's the fixed cost of a larger image.

In absolute terms it's +56 µs. For the path that actually matters, complete-word on a real spec, I measured 117.8 → 118.1 ms earlier against mise's 208 KB spec — the startup delta is a rounding error next to parsing.

Your call, and I'd rather you made it than have me pick:

1. Take the 56 µs. It buys an MCP server in the default binary, which is the only way an agent finds it without extra setup.
2. Feature-gate rmcp, default off. Startup returns to baseline for anyone who builds without it — but usage mcp then doesn't exist in the standard build or the released binaries unless you enable it there, which puts the cost right back on the builds people use. I don't think this buys anything real, but it's available.

Happy to do either. What I won't do is quietly widen the gate to make my own check green.

This comment was generated by an AI coding assistant.